home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu229.dms / pu229.adf / JPeg / README < prev    next >
Text File  |  1991-12-03  |  15KB  |  317 lines
  1. The Independent JPEG Group's JPEG software
  2. ==========================================
  3.  
  4. README for release of  7-Oct-91
  5. ===============================
  6.  
  7. This distribution contains the first public release of the Independent JPEG
  8. Group's free JPEG software.  You are welcome to redistribute this software and
  9. to use it for any purpose, subject to the conditions under LEGAL ISSUES, below.
  10.  
  11. This software is still undergoing revision.  Updated versions may be obtained
  12. by anonymous FTP to uunet.uu.net; look under directory /graphics/jpeg.  This
  13. particular version will be archived as jpegsrc.v1.tar.Z.  If you don't have
  14. access to Internet FTP, UUNET's archives are also available via UUCP; contact
  15. postmaster@uunet.uu.net for information on retrieving files that way.
  16.  
  17. Please report any problems with this software to jpeg-info@uunet.uu.net.
  18.  
  19. If you intend to become a serious user of this software, please contact
  20. jpeg-info@uunet to be added to our electronic mailing list.  Then you'll be
  21. notified of updates and have a chance to participate in discussions, etc.
  22.  
  23. This software is the work of Tom Lane, Philip Gladstone, Luis Ortiz, and other
  24. members of the independent JPEG group.
  25.  
  26.  
  27. DISCLAIMER
  28. ==========
  29.  
  30. THIS SOFTWARE IS NOT COMPLETE NOR FULLY DEBUGGED.  It is not guaranteed to be
  31. useful for anything, nor to be compatible with subsequent releases, nor to be
  32. an accurate implementation of the JPEG standard.  (See LEGAL ISSUES for even
  33. more disclaimers.)
  34.  
  35.  
  36. WHAT'S HERE
  37. ===========
  38.  
  39. This distribution contains software to implement JPEG image compression and
  40. decompression.  JPEG is a standardized compression method for full-color and
  41. gray-scale images.  JPEG is intended for "real-world" scenes; cartoons and
  42. other non-realistic images are not its strong suit.  JPEG is lossy, meaning
  43. that the output image is not necessarily identical to the input image.  Hence
  44. you should not use JPEG if you have to have identical output bits.  However,
  45. on typical images of real-world scenes, very good compression levels can be
  46. obtained with hardly any visible change, and amazingly high compression levels
  47. can be obtained if you can tolerate a low-quality image.  For more details,
  48. see the references, or just experiment with various compression settings.
  49.  
  50. The software implements JPEG baseline and extended-sequential compression
  51. processes.  Provision is made for supporting all variants of these processes,
  52. although some uncommon parameter settings aren't implemented yet.  For legal
  53. reasons, we are not distributing code for the arithmetic-coding process; see
  54. LEGAL ISSUES.  At present we have made no provision for supporting the
  55. progressive or lossless processes defined in the standard.
  56.  
  57. The present software is still largely in the prototype stage.  It does not
  58. support all possible variants of the JPEG standard, and some functions have
  59. rather slow and/or crude implementations.  However, it is useful already.
  60.  
  61. The emphasis in designing this software has been on achieving portability and
  62. flexibility, while also making it fast enough to be useful.  We have not yet
  63. undertaken serious performance measurement or tuning; we intend to do so in
  64. the future.
  65.  
  66.  
  67. This software can be used on several levels:
  68.  
  69. * As canned software for JPEG compression and decompression.  Just edit the
  70.   Makefile and configuration files as needed (see SETUP), compile and go.
  71.   Members of the independent JPEG group will improve the out-of-the-box
  72.   functionality as time goes on.
  73.  
  74. * As the basis for other JPEG programs.  For example, you could incorporate
  75.   the decompressor into a general image viewing package by replacing the
  76.   output module with write-to-screen functions.  For an implementation on
  77.   specific hardware, you might want to replace some of the inner loops with
  78.   assembly code.  For a non-command-line-driven system, you might want a
  79.   different user interface.  (Members of the group will be producing Macintosh
  80.   and Amiga versions with appropriate user interfaces, for example.)
  81.  
  82. * As a toolkit for experimentation with JPEG and JPEG-like algorithms.  Most
  83.   of the individual decisions you might want to mess with are packaged up into
  84.   separate modules.  For example, the details of color-space conversion and
  85.   subsampling techniques are each localized in one compressor and one
  86.   decompressor module.  You'd probably also want to extend the user interface
  87.   to give you more detailed control over the JPEG compression parameters.
  88.  
  89. In particular, we welcome the use of this software as the basis for commercial
  90. products; no royalty is required.
  91.  
  92.  
  93. USAGE
  94. =====
  95.  
  96. The user interface is pretty minimal at this point.  We haven't bothered to
  97. generate manual-page files since the switches badly need redesign.  At the
  98. moment, things work like this:
  99.  
  100. There are two programs, cjpeg to compress an image file into JPEG format,
  101. and djpeg to decompress.
  102.  
  103. On Unix systems, you say:
  104.    cjpeg [switches] [imagefile] >jpegfile
  105.    djpeg [switches] [jpegfile]  >imagefile
  106. The programs read the specified input file, or standard input if none is
  107. named.  They always write to standard output (with trace/error messages to
  108. standard error).  These conventions are handy for piping images between
  109. programs.
  110.  
  111. On PC, Macintosh, and Amiga systems, you say:
  112.    cjpeg [switches] imagefile jpegfile
  113.    djpeg [switches] jpegfile  imagefile
  114. i.e., both input and output files are named on the command line.  This style
  115. is a little more foolproof, and it loses no functionality if you don't have
  116. pipes.  You can get this style on Unix too, if you prefer, by defining
  117. TWO_FILE_COMMANDLINE in jconfig.h or in the Makefile.  You MUST use this style
  118. on any system that doesn't cope well with binary data fed through
  119. stdin/stdout.
  120.  
  121. Currently supported image file formats include raw-format PPM, raw-format PGM
  122. (for monochrome images), and GIF.  cjpeg recognizes the input image format
  123. automatically, but you have to tell djpeg which format to generate.
  124.  
  125. The only JPEG file format currently supported is a raw JPEG data stream.
  126. Unless modified, the programs use the JFIF conventions for variables left
  127. unspecified by the JPEG standard.  (In particular, cjpeg generates a JFIF APP0
  128. marker.)  Support for the JPEG-in-TIFF format will probably be added at some
  129. future date.
  130.  
  131. The command line switches for cjpeg are:
  132.  
  133.    -I    Generate noninterleaved JPEG file (not yet supported).
  134.  
  135.    -Q quality  Scale quantization tables to adjust quality.
  136.          Quality is 0 (worst) to 100 (best); default is 75.
  137.          (See below for more info.)
  138.  
  139.    -a    Use arithmetic coding rather than Huffman coding.
  140.          (Not currently supported, see LEGAL ISSUES.)
  141.  
  142.    -o    Perform optimization of entropy encoding parameters.
  143.          Without this, default Huffman or arithmetic
  144.          parameters are used.  -o makes the JPEG file a tad
  145.          smaller, but compression uses much more memory.
  146.          Image quality is unaffected by -o.
  147.  
  148.    -d    Enable debug printout.  More -d's give more printout.
  149.  
  150. Typically you'd use -Q settings of 50 or 75 or so.  -Q 100 will generate a
  151. quantization table of all 1's, meaning no quantization loss; then any
  152. differences between input and output images are due to subsampling or to
  153. roundoff error in the DCT or colorspace-conversion steps.  -Q values below 50
  154. may be useful for making real small, low-quality images.  Try -Q 2 (or so) for
  155. some amusing Cubist effects.  (Note that -Q values below about 25 generate
  156. 2-byte quantization tables, which are not decodable by pure baseline JPEG
  157. decoders.  cjpeg emits a warning message when you give such a -Q value.)
  158.  
  159. The command line switches for djpeg are:
  160.  
  161.    -G    Select GIF output format (implies -q, with default
  162.          of 256 colors).
  163.  
  164.    -b    Perform cross-block smoothing.  This is quite
  165.          memory-intensive and only seems to improve the image
  166.          at very low quality settings (-Q 10 to 20 or so).
  167.  
  168.    -g    Force gray-scale output even if input is color.
  169.  
  170.    -q N     Quantize to N colors.
  171.  
  172.    -D    Use Floyd-Steinberg dithering in color quantization.
  173.  
  174.    -2    Use two-pass color quantization (not yet supported).
  175.  
  176.    -d    Enable debug printout.  More -d's give more printout.
  177.  
  178. Color quantization currently uses a rather shoddy algorithm (although it's not
  179. so horrible when dithered).  Because of this, the GIF output mode is not
  180. recommended in the current release, except for gray-scale output.  You can get
  181. better results by applying ppmquant to the unquantized (PPM) output of djpeg,
  182. then converting to GIF with ppmtogif.  We expect to provide a considerably
  183. better quantization algorithm in a future release.
  184.  
  185. Note that djpeg *can* read noninterleaved JPEG files even though cjpeg can't
  186. yet generate them.  For most applications this is a nonissue, since hardly
  187. anybody seems to be using noninterleaved format.
  188.  
  189. On a non-virtual-memory machine, you may run out of memory if you use -I or -o
  190. in cjpeg, or -q ... -2 in djpeg, or try to read an interlaced GIF file.  This
  191. will be addressed eventually by replacing jvirtmem.c with something that uses
  192. temporary files for large images (see TO DO).
  193.  
  194.  
  195. REFERENCES
  196. ==========
  197.  
  198. The best and most readily available introduction to the JPEG compression
  199. algorithm is Wallace's article in the April '91 CACM:
  200.    Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",
  201.    Communications of the ACM, April 1991 (vol. 34 no. 4), pp. 30-44.
  202. (Adjacent articles in that issue discuss MPEG motion picture compression,
  203. applications of JPEG, and related topics.)  We highly recommend reading that
  204. article before looking at any of the JPEG software.
  205.  
  206. For more detail about the JPEG standard you pretty much have to go to the
  207. draft standard, which is not nearly as intelligible as Wallace's article.
  208. The current version is ISO/IEC Committee Draft CD 10918-1 dated 1991-03-15.
  209. The standard is not presently available electronically; you must order a paper
  210. copy through ISO.
  211.  
  212. The JPEG standard does not specify all details of an interchangeable file
  213. format.  For the omitted details we follow the "JFIF" conventions, revision
  214. 1.01.  A copy of the JFIF spec is available from:
  215.    Literature Department
  216.    C-Cube Microsystems, Inc.
  217.    399A West Trimble Road
  218.    San Jose, CA  95131
  219.    (408) 944-6300
  220. Requests can also be e-mailed to info@c3.pla.ca.us (this address good after
  221. 10/10/91).  The same source can supply copies of the draft JPEG-in-TIFF specs.
  222.  
  223. If you want to understand this implementation, start by reading the
  224. "architecture" documentation file.  Please read "codingrules" if you want to
  225. contribute any code.
  226.  
  227.  
  228. SUPPORTING SOFTWARE
  229. ===================
  230.  
  231. You will probably want Jef Poskanzer's PBMPLUS image software; this provides
  232. many useful operations on PPM-format image files.  In particular, it can
  233. convert PPM images to and from a wide range of other formats.  You can FTP
  234. this free software from export.lcs.mit.edu (contrib/pbmplus*.tar.Z) or
  235. ftp.ee.lbl.gov (pbmplus*.tar.Z).
  236.  
  237. If you are using X Windows you might want to use the xv or xloadimage viewers
  238. to save yourself the trouble of converting PPM to some other format.
  239. Both of these can be found in the contrib directory at export.lcs.mit.edu.
  240.  
  241.  
  242. LEGAL ISSUES
  243. ============
  244.  
  245. The authors make NO WARRANTY or representation, either express or implied,
  246. with respect to this software, its quality, accuracy, merchantability, or
  247. fitness for a particular purpose.  This software is provided "AS IS", and you,
  248. its user, assume the entire risk as to its quality and accuracy.
  249.  
  250. This software is copyright (C) 1991, Thomas G. Lane.
  251. All Rights Reserved except as specified below.
  252.  
  253. Permission is hereby granted to use, copy, modify, and distribute this
  254. software (or portions thereof) for any purpose, without fee, subject to these
  255. conditions:
  256. (1) If any part of the source code for this software is distributed, then this
  257. README file must be included, with this copyright and no-warranty notice
  258. unaltered; and any additions, deletions, or changes to the original files
  259. must be clearly indicated in accompanying documentation.
  260. (2) If only executable code is distributed, then the accompanying
  261. documentation must state that "this software is based in part on the work of
  262. the Independent JPEG Group".
  263. (3) Permission for use of this software is granted only if the user accepts
  264. full responsibility for any undesirable consequences; the authors accept
  265. NO LIABILITY for damages of any kind.
  266.  
  267. Permission is NOT granted for the use of any author's name or author's company
  268. name in advertising or publicity relating to this software or products derived
  269. from it.  This software may be referred to only as "the Independent JPEG
  270. Group's software".
  271.  
  272. We specifically permit and encourage the use of this software as the basis of
  273. commercial products, provided that all warranty or liability claims are
  274. assumed by the product vendor.
  275.  
  276.  
  277. ansi2knr.c is included in this distribution by permission of L. Peter Deutsch,
  278. sole proprietor of its copyright holder, Aladdin Enterprises of Menlo Park, CA.
  279. ansi2knr.c is NOT covered by the above copyright and conditions, but instead
  280. by the usual distribution terms of the Free Software Foundation; principally,
  281. that you must include source code if you redistribute it.  (See the file
  282. ansi2knr.c for full details.)  However, since ansi2knr.c is not needed as part
  283. of any product generated from the JPEG code, this does not limit you more than
  284. the foregoing paragraphs do.
  285.  
  286.  
  287. It appears that the arithmetic coding option of the JPEG spec is covered by
  288. patents held by IBM, and possibly also patents of AT&T and Mitsubishi.  Hence
  289. arithmetic coding cannot legally be used without obtaining one or more
  290. licenses.  For this reason, support for arithmetic coding has been removed
  291. from the free JPEG software.  (Since arithmetic coding provides only a
  292. marginal gain over the unpatented Huffman mode, it is unlikely that very many
  293. people will choose to use it.  If you do obtain such a license, contact
  294. jpeg-info@uunet.uu.net for a copy of our arithmetic coding modules.)  So far
  295. as we are aware, there are no patent restrictions on the remaining code.
  296.  
  297.  
  298. TO DO
  299. =====
  300.  
  301. Many of the modules need fleshing out to provide more complete
  302. implementations, or to provide faster paths for common cases.  The greatest
  303. needs are for (a) decent color quantization, and (b) a memory manager
  304. implementation that can work in limited memory by swapping "big" images to
  305. temporary files.  I (Tom Lane) am going to work on color quantization next.
  306. Volunteers to write a PC memory manager, or to work on any other modules, are
  307. welcome.
  308.  
  309. We'd appreciate it if people would compile and check out the code on as wide a
  310. variety of systems as possible, and report any portability problems
  311. encountered (with solutions, if possible).  Checks of file compatibility with
  312. other JPEG implementations would also be of interest.  Finally, we would
  313. appreciate code profiles showing where the most time is spent, especially on
  314. unusual systems.
  315.  
  316. Please send bug reports, offers of help, etc. to jpeg-info@uunet.uu.net.
  317.